#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Copyright (c) 2016-2018, Niklas Hauser
# Copyright (c) 2017-2018, Fabian Greif
#
# This file is part of the modm project.
#
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
# -----------------------------------------------------------------------------


def init(module):
    module.name = ":processing:resumable"
    module.description = FileReader("module.md")

def prepare(module, options):
    module.depends(":architecture:assert", ":architecture:fiber")

    module.add_option(
        BooleanOption(
            name="check_nesting_depth",
            default=True,
            description=descr_nesting_depth))

    return True

def validate(env):
    if not env.get(":processing:protothread:use_fiber", True):
        env.log.warning(descr_deprecated)

def build(env):
    env.outbasepath = "modm/src/modm/processing/resumable"
    if env.get(":processing:protothread:use_fiber", True):
        env.copy("macros_fiber.hpp", "macros.hpp")
        env.copy("resumable_fiber.hpp", "resumable.hpp")
    else:
        env.copy("macros.hpp")
        env.copy("resumable.hpp")
        env.template("nested_resumable.hpp.in")
    env.copy("../resumable.hpp")


# ============================ Option Descriptions ============================
descr_nesting_depth = """# Check nesting call depth

Nested resumable functions protect against memory corruption by checking if the
nesting level is within the allocated nesting level depth, on first entry to
the function. If the allocated nesting level is exceeded, the assertion
`resumable.begin.nesting` fails.

You may disable this behavior by disabling this check, then instead of the
assertion, the function on entry returns the `modm::rf::NestingError` state value.
`PT_CALL()` and `RF_CALL()` macros will respond to this error by stopping
function polling and just continuing program execution.

!!! info "Performance Penalty"
    This check is performed during the call to `RF_BEGIN(N)`, so exactly once
    on function entry and not during every polling call, so the performance
    penalty is relatively small.
"""

descr_deprecated = """

        ####  Resumable Functions are deprecated!  ####

Unfortunately GCC12 is the last version that supported the way we implemented
Resumables. Since GCC13 the implementation does not compile anymore and cannot
be fixed without significant breaking changes.

Please port your code to use `modm:processing:fiber` instead.
"""
